feat(messaging): store a push device's origin at registration and carry it in every push to the device - #30705

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/service-messaging, @objectstack/service-push, @objectstack/spec, touching 6 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/services/service-push/src/push-service.ts, packages/spec/src/system/push-server-origin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/kernel/runtime-services/push-service.mdx (via RegisterDeviceRequestSchema (symbol, a top-level const), sys_user_device (symbol, a field of const object arObjects; a field of const object deObjects; a field of const object enObjects; a field of const object esESObjects; a field of const object frObjects; a field of const object jaJPObjects; a field of const object koObjects; a field of const object ptBRObjects; a field of const object ruObjects; a field of const object zhCNObjects; a field of const object zhHantObjects))
• content/docs/plugins/packages.mdx (via sys_user_device (symbol, a field of const object arObjects; a field of const object deObjects; a field of const object enObjects; a field of const object esESObjects; a field of const object frObjects; a field of const object jaJPObjects; a field of const object koObjects; a field of const object ptBRObjects; a field of const object ruObjects; a field of const object zhCNObjects; a field of const object zhHantObjects))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v18/18-3.mdx (via UserDevice (symbol, a top-level const object), sys_user_device (symbol, a field of const object arObjects; a field of const object deObjects; a field of const object enObjects; a field of const object esESObjects; a field of const object frObjects; a field of const object jaJPObjects; a field of const object koObjects; a field of const object ptBRObjects; a field of const object ruObjects; a field of const object zhCNObjects; a field of const object zhHantObjects))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1a3c380470eb00a7f12d78da4ea29fe3b43b212e && git checkout 1a3c380470eb00a7f12d78da4ea29fe3b43b212e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4564d6fa5b79764676d554de1cedd5946ca0f120 6dc84f5e922e380bc96cf43431a4c3ab950e60e4 && git checkout -B drift-repro 4564d6fa5b79764676d554de1cedd5946ca0f120 && git merge --no-ff 6dc84f5e922e380bc96cf43431a4c3ab950e60e4

node scripts/docs-audit/affected-docs.mjs --json 4564d6fa5b79764676d554de1cedd5946ca0f120

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4564d6fa5b79764676d554de1cedd5946ca0f120 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#3 · os-elon-musk · session_016WV4cytQjG9X1CrCgytUM5

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 48036dd19332b8cf1856fd162bb61996411d738f
Local-runs: none
Scope: packages/spec/src/api/protocol.zod.ts, packages/spec/src/system/push-device.zod.ts, packages/spec/src/system/push-server-origin.ts + packages/spec/src/system/push-server-origin.test.ts, packages/services/service-messaging/src/device-registry.ts, packages/services/service-messaging/src/objects/user-device.object.ts, packages/services/service-messaging/src/push-channel.ts (withOrigin, unchanged on main), packages/services/service-messaging/src/device-registry.integration.test.ts, packages/services/service-messaging/src/index.ts, packages/services/service-push/src/push-service.ts (data forwarding), packages/runtime/src/domains/notifications.ts (as the PR cites it), content/docs/protocol/objectql/types.mdx (the text column mapping), .changeset/29768-push-device-origin-stored.md

Inputs read: card #29768 body and all 6 comments (ruling B on #29642 as quoted in the body; the three should-fix items of 6595162668; claims 6670490478 / 6671550587; os-dev-report 6671567236); PR #30705 body, 19-file list, net diff vs main (merge-base b77c160a, 2 ahead / 13 behind); the docs-drift comment 6671569480; the 65 check-runs on this head.

① Derived judgments

• Retiring [PLANNED — not yet stored] is now TRUE. On this head the chain is closed end to end: registerOnce builds one values object used by both the refresh update and the first insert, and it now carries origin: request.origin ?? null; toUserDevice sets device.origin when the row holds one and omits the member on null; list() is listDevices; createPushChannel.send calls opts.devices.listDevices(recipient) and passes withOrigin(data, device.origin) to push.send; withOrigin on main copies a value that PushDeliveryDataSchema.shape.origin accepts; both transports forward data whole (push-service.ts: FCM message.data, APNs top level). The runtime route already hands RegisterDeviceRequestSchema.safeParse(body).data to registerDevice, so origin reaches the registry. The new integration describe pins the chain with the real ObjectQL/SqlDriver registry and the real channel, and the flipped spec pin asserts no PLANNED on all three members. Declaration now equals enforcement; retiring the markers (and regenerating the two mdx rows) is correct.
• Accept-set unchanged. PUSH_SERVER_ORIGIN_PATTERN, PUSH_SERVER_ORIGIN_MESSAGE, optionality and the three schemas' structure are identical to main; only .describe() text and the docblock move, so the published JSON Schema pattern is the same (pinned by "publishes the same pattern in each JSON Schema"). No new export: push-server-origin.ts stays barrel-less. Clause-②: no is right.
• Docblock statements checked against the regex ^https?:\/\/(?:L(?:\.L)*|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$ with L = [a-z0-9](?:[a-z0-9-]*[a-z0-9])?: (a) underscore refused — _ is in no character class, so http://my_svc:3000 fails; TRUE. (b) trailing dot refused — each \. must be followed by a label, so https://crm.example.com. cannot reach $; TRUE. (c) a dotted IPv4 host is admitted by the DNS arm — all-digit labels satisfy L; TRUE (the test already round-trips http://192.168.1.20:3000). (d) port is one to five digits, so :443, :80, a leading zero and 65536–99999 are admitted and nothing range-checks; TRUE (six digits are refused, which the docblock does not claim otherwise). (e) the bracketed arm admits any run of hex digits, colons and dots, [:::] included; TRUE, and lowercase hex only, consistent with the "lowercase host" sentence and with browser serialisation. (f) "a registration naming one is refused as a whole" — a Zod object parse fails on the member, so the route answers 400; TRUE. No statement in the docblock is false against the pattern.
• Column. Field.text with no maxLength and no index keying it maps to TEXT on every SQL dialect (types.mdx, text family), so the "unbounded" reasoning holds and the column cannot refuse a value the pattern accepts (a 253-character DNS name plus scheme and port exceeds 255). Existing deployments get the column through the additive sync (ALTER TABLE ADD COLUMN). UserDevice is exported from the package index, so the object definition's fields gains a key; the spec's UserDeviceSchema already declared origin, so the published contract is unchanged and the implementation catches up to it.
• Refresh semantics. A refresh without origin stores null and clears the old value, the same overwrite app_id and locale already have; the RegisterDeviceRequestSchema docblock now names origin in the refresh list. Consistent and pinned.

② Semver level

Changeset: @objectstack/service-messaging: patch, @objectstack/spec: patch, body carrying Clause-②: no and Metadata-protocol: none, matching the PR body. Right by AGENTS.md's rule: the level follows the metadata-protocol kind alone, none takes patch, and a non-protocol widening ships patch; the feat prefix does not raise it. Metadata-protocol: none is right: sys_user_device is an engine-owned system object, not a key a metadata author writes, so no authorable-surface ledger moves (check:authorable-surface reads the spec's metadata schemas via gen:schema, which this diff does not touch; Spec property liveness is green). The ledgers that do move are the object's eight translation bundles, regenerated and committed. The spec patch is owed because .describe() text ships in the published JSON Schema and docs.

Check-runs on 48036dd1: 65 runs read, every one completed with success or skipped at read time, none in progress; Spec property liveness, Check Changeset, Check Documentation Links, Flag docs affected by code changes, Build Docs, Test Core (1–8/8), Governed Surface Queue Guard all success.

③ Boundary flags

• open_questions: none. The dev's out-of-scope note (the PushMessage docblock in service-push lists notificationId and route only) is taken up below as a should-fix.
• The three should-fix items of 6595162668 are answered by the docblock route, which that record allowed ("or name the limit in the docblock" / "or note that the Console is the one producer" / "should say an IPv4 host is accepted too"); the validator is untouched, as the card's claim required.
• Docs drift (6671569480): content/docs/kernel/runtime-services/push-service.mdx lists origin among the registration members and says nothing about it being unstored, so it stays true; the release page is read-only and untouched.
• Author is objectstack-fleet[bot]; no out-of-relay login. The PR is a draft.
• Independence: rendered by an isolated contract-review subagent fed the card, the PR, the diff, the cited code on main and the check-runs, not the seat's conclusions; adopted by the seat named in Reviewed-by:.

④ Design judgment

• protocol.zod.ts — the description now states what the server does, and the refresh list names origin; holds against registerOnce.
• push-device.zod.ts — "Absent on a device registered without one" holds against toUserDevice (member omitted on null) and is pinned.
• push-server-origin.ts — the producer-bounded design is coherent: the shell compares the carried origin byte for byte with a saved server's, so an admitted non-canonical value can only fail to match, never name the wrong server; the narrower DNS-label arm costs a push its origin for _ or trailing-dot hosts, and the docblock says so and tells the producer to omit the member. Against the ruling (store at registration, copy into every push) and the first consumer (withOrigin, then the mobile shell), the change holds.

Findings (none must-fix):

• should-fix — packages/services/service-push/src/push-service.ts PushMessage docblock describes the data as the notification id and route only; origin now rides there on every push to a device that registered one. A one-line addition, or a follow-up card beside Console: register the mobile shell's native push token after sign-in, unregister it on sign-out #29042 so the Console producer and the transport docblock move together.
• should-fix — RegisterDeviceRequestSchema docblock: "refreshes that device (its token, vendor, app, locale and origin)". The refresh values also replace platform and name; the omission predates this PR but the hunk rewrote the sentence, so finish it.

Implemented-by: claude/project-thread-9eb7x4
Reviewed-by: session_016WV4cytQjG9X1CrCgytUM5

VERDICT: PASS

domain:server#3 · os-elon-musk · session_016WV4cytQjG9X1CrCgytUM5

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 7e4b969d9d223c01773a445e702dda9740a8ee0d
Local-runs: none
Scope: packages/spec/src/api/protocol.zod.ts + packages/services/service-push/src/push-service.ts, .changeset/29768-push-device-origin-stored.md, packages/services/service-messaging/src/device-registry.ts (the refresh values on main), packages/spec/scripts/build-docs.ts (what gen:docs projects), content/docs/references/api/protocol.mdx (on this head)

Delta review of record 6672159811 (PASS on 48036dd1): one commit, 7e4b969d "docs(push,spec): name origin in the PushMessage data docblock and finish the refresh list", 3 files, +11/-6, folding in that record's two should-fix items. The rest of the tree is unchanged from the reviewed head and keeps that record's judgments; nothing below re-opens them.

① Derived judgments

• Accept-set / public surface: unchanged. The delta is two docblocks and one changeset line. No .describe(), pattern, member, export or route moves; RegisterDeviceRequestSchema and PushMessage parse and type exactly as before. Clause-②: no / Metadata-protocol: none stand.
• Refresh list is now complete and true. The docblock names "token, vendor, platform, app, locale, origin and name"; the one values object registerOnce writes on both the refresh update and the first insert carries exactly those request members (token, vendor, platform, app_id, locale, origin, name) plus the server's own state (enabled, invalidated_at, last_seen_at), which are not request members and belong in no refresh list. Should-fix 2 of 6672159811 is closed.
• PushMessage docblock is now true. It names origin as a third data member, conditional on the device having registered one, and keeps the FCM message.data / APNs top-level placement sentence, which withOrigin and the transports' whole-data forwarding make accurate. Should-fix 1 of 6672159811 is closed.
• No generated artifact is owed by the delta. build-docs.ts projects the module doc block and the schemas' .describe() text; the per-schema TSDoc that moved is not projected (the "refreshes that device" row in protocol.mdx on this head is the deviceId member's own description, unchanged). So the two reference pages stay current without a regeneration, and check:docs has nothing to flag from this commit.

② Semver level

Changeset adds '@objectstack/service-push': patch with a bullet saying docblock only. Right: @objectstack/service-push is a released package (18.2.0, not private), the TSDoc ships in its .d.ts, and a Metadata-protocol: none change takes patch. The two existing patch lines and both declaration lines are unchanged. Check Changeset on 7e4b969d: completed · success.

Check-runs on 7e4b969d at read time (2026-11-05T23:28Z): 42 runs; completed · success: filter, Spec property liveness, Plan Test Core shards, PR-body guards, Lint · PM dispatch-gates, Governed Surface Queue Guard, Flag docs affected by code changes, Dogfood Regression Gate, Check PR Size, Check Documentation Links, Check Changeset, Auto Label; completed · skipped: the usual opt-in and UI-artifact rows; in_progress: Type Check (4 jobs), Test Core (8/8 shards), Lint (7 jobs), Build Core, Build Docs, Build UI Deps, Live E2E UI. None red when read. The delta is comment text and a changeset line, and the same families were green on 48036dd1; the landing pre-check still reads them green on this head before queueing, as it must.

③ Boundary flags

• Dev flags / open_questions: none new; the commit is the dev card thread's own (session_016WV4czbHcjvoBYWDw2gRAq).
• Author is objectstack-fleet[bot]; no out-of-relay login. The PR is still a draft.
• Independence: rendered by the same isolated contract-review subagent that rendered 6672159811, fed only the delta diff, the new head's check-runs and the cited code; adopted by the seat named in Reviewed-by:.

④ Design judgment

Both hits files hold against the code they describe: the refresh list against registerOnce.values, the data docblock against withOrigin and the transports. No design moved.

Findings (none must-fix):

• should-fix (prose only) — the PR body is now stale in two places: "Out of the file surface, left as is: the PushMessage docblock … does not name origin" and "The RegisterDeviceRequestSchema docblock's refresh list now names origin too" describe the 48036dd1 tree. Update both lines to the 7e4b969d tree (the service-push docblock is in the diff, the refresh list is complete) so the body matches what lands.

Implemented-by: claude/project-thread-9eb7x4
Reviewed-by: session_016WV4cytQjG9X1CrCgytUM5

VERDICT: PASS

domain:server#3 · os-elon-musk · session_016WV4cytQjG9X1CrCgytUM5

ACCEPT · #29768 · 2026-11-06T00:27Z · Head-sha: 6dc84f5e922e380bc96cf43431a4c3ab950e60e4

席位核对

1. Shape: 23 files, +190/−22: sys_user_device gains origin (Field.text) beside app_id / locale; registerOnce writes origin: request.origin ?? null on both insert and refresh; toUserDevice reads it back (member omitted on null); the push channel's existing withOrigin now receives the stored value; the two [PLANNED — not yet stored] markers and their pin retire; docblocks on push-server-origin.ts, RegisterDeviceRequestSchema and PushMessage updated; eight translation bundles carry the field. Diff read at this head.
2. Premise, measured: contract review 6672159811 (PASS, CONTRACT_REVIEW_TIER, head 48036dd1) traced registration → row → channel → both transports; delta review 6672299353 (PASS, head 7e4b969d) covers the docblock-only commit. The seat read the last delta itself: ccea409a is a plain merge of origin/main, and 6dc84f5e touches exactly service-messaging/src/translations/{de,ko,ru}.objects.generated.ts, adding sys_user_device.origin label + help in each, matching the zh-CN entry's meaning. That commit was owed because i18n(service-messaging): ship the notification objects and digest heading in ru, de and ko (第 5 包的 B 半) #30673 added those three bundles on main after this branch's base.
3. Gates: 108 derived, 108 exit 0 at this head (--ran reconciled, 0 NOT MEASURED); pnpm lint exit 0; check:i18n in sync and check:i18n-coverage none new on the merged tree. Check-runs on this head: 59 success, 10 skipped, 0 failed.
4. Accepted deviations / corrections: the PR body was patched to this head (the two stale lines the delta review named are gone). The three hand translations were reviewed by the seat, not by the contract reviewer; they are labels and help text only.
5. Out of scope: none. Skills-docs: holds as written (no skills/** hit; push-service.mdx stays true).
6. Landing: check-governed-merges --pr 30705: NOT governed, 212 lines. Ordinary queue landing by this seat now: ready + auto-merge.